Configuring SequeLink® Server for JDBC Socket

The SequeLink Server for JDBC Socket must be configured before it can be used.

This information applies to Windows 200x, and Windows XP.

Configuring a SequeLink® Service for JDBC Socket on Windows

You can use one SequeLink Server for JDBC Socket to connect with different JDBC drivers. For each JDBC driver you want to access, make a new data source and add the JDBC driver to the CLASSPATH. Changing the CLASSPATH requires a restart of the SequeLink Service for JDBC Socket.

Setting Up the JDBC Driver Environment

Before setting up the SequeLink Server for JDBC Socket environment, ensure you have set up the backend JDBC driver environment and that you can make a connection to this JDBC driver.

Verifying the JDBC Driver Environment

The ivcheckjdbcdriver utility is included in the installation package, and is located in the directory where the installer resides.

Run the ivcheckjdbcdriver utility to make a JDBC connection to your backend JDBC driver. This utility will make a connection, check a number of requirements of the backend JDBC driver and return you the information you need to enter during the configuration of a SequeLink Service for JDBC Socket.

Use this utility before configuring the SequeLink Server for JDBC Socket. You must enter the following configuration information:

When the ivcheckjdbcdriver script has verified these settings and successfully made a connection, use these settings for the configuration of your SequeLink Server for JDBC Socket. Read the note included in the information that is returned for specific driver issues.

For more information about the ivcheckjdbcdriver utility, refer to the SequeLink Troubleshooting Guide and Reference.

Configuring the SequeLink® Server for JDBC Socket

  1. Create a new SequeLink JDBC Socket Service using one of the SequeLink administration tools. Enter the service name and the TCP/IP port and register the SequeLink service.

    2. During the creation of the SequeLink JDBC Socket Service, the SequeLink JDBC Socket ServiceTemplate (configured during the installation) is copied. In the following steps, check these values or correct these values for your specific service.

  2. The SequeLink Server for JDBC Socket starts up the JVM and therefore it needs the path to be set in the SequeLink configuration. This is done via a SequeLink Service environment variable.

    3. ServiceEnvironmentVariable:

    PATH= java_install_dir\jre\bin; java_install_dir\jre\bin\server

    This path must contain the jvm.dll and all its dependencies.

  3. The SequeLink Service for JDBC Socket attempts to load the JDBC drivers, defined in the server side data sources. All JDBC drivers that need to be accessed must reside in the CLASSPATH. This environment variable needs to be defined in the SequeLink service configuration. Add the CLASSPATH and the classes used by the SequeLink service for JDBC Socket. These classes are installed in install_dir\bin\classes.

    4. For example, to configure SequeLink with the Apache Derby 10 driver:

    CLASSPATH=C:\Program Files\Apache\Derby\derby; C:\Program Files\DataDirect\slserver60\bin\classes

  4. (Optional) If you want to specify specific settings for the JVM, set the SequeLink Service environment variable SL_JAVA_OPTIONS.

    5. For example, to set the maximum heap size for the JVM:

    SL_JAVA_OPTIONS=-Xmx32M

    For Apache Derby 10, you may have to specify the database directory:

    SL_JAVA_OPTIONS= -Dderby.system.home=C:\Data\Derby

  5. Create a new server side data source or use the Default server side data source.
  6. Specify the required server-side data source settings for the JDBC driver.
    • DataSourceSOCJDBCConnectionURL

      • For example, for Apache Derby 10:

      DataSourceSOCJDBCConnectionURL = jdbc:dd-derby10:salesdb

      Where database is the database name you want to access.

    • DataSourceSOCJDBCDriverClassName

      • For example, for Apache Derby 10:

      DataSourceSOCJDBCDriverClassName = com.ddtek.jdbc.derby10.DerbyDriver

      See "SequeLink® Service Attributes" for information about these attributes.

  7. Specify specific, server-side data source settings, for your JDBC driver, for example, DataSourceSOCJDBCDbPropertiesName=derby.

    8. See "SequeLink® Service Attributes" for information about these attributes.

  8. When the SequeLink Service for JDBC Socket and its server-side data sources are set up, you can save your SequeLink configuration and (re)start the SequeLink Service for JDBC Socket.
  9. Run your ODBC, JDBC, .NET or ADO application and access the databases through your JDBC backend driver using the SequeLink Service for JDBC Socket. Refer to the SequeLink Developer's Guide for additional information.

NOTE: If you want to run an ADO application, refer to the SequeLink Installation Guide, for information on completing the JDBC Socket Installation for SequeLink Client for ADO.

This information applies to Windows and UNIX.

Configuring a SequeLink® Service for JDBC Socket on Linux/UNIX

You can use one SequeLink Server for JDBC Socket to connect with different JDBC drivers. For each JDBC driver you want to access, make a new data source and add the JDBC driver to the CLASSPATH. Changing the CLASSPATH requires a restart of the SequeLink Service for JDBC Socket.

Setting Up the JDBC Driver Environment

Before setting up the SequeLink Server for JDBC Socket environment, ensure you have set up the backend JDBC driver environment and that you can make a connection to this JDBC driver.

Verifying the JDBC Driver Environment

The ivcheckjdbcdriver utility is packaged with SequeLink Server for JDBC Socket for Linux/UNIX, and installed after the untar.

Run the ivcheckjdbcdriver utility to make a JDBC connection to your backend JDBC driver. This utility will make a connection, check a number of requirements of the backend JDBC driver and return the information you need to enter during the configuration of a SequeLink Service for JDBC Socket.

Use the ivcheckjdbcdriver utility before configuring the SequeLink Server for JDBC Socket. You must enter the following configuration information:

When the ivcheckjdbcdriver script has verified these settings and successfully made a connection, you can use these settings for the configuration of your SequeLink Server for JDBC Socket. Read the note included in the information that is returned for specific driver issues.

For more information about the ivcheckjdbcdriver utility, refer to the SequeLink Troubleshooting Guide and Reference.

Configuring the SequeLink® Server for JDBC Socket

  1. Create a new SequeLink JDBC Socket Service using one of the SequeLink administration tools. Enter the service name and the TCP/IP port and register the SequeLink service.

    2. During the creation of the SequeLink JDBC Socket Service, the SequeLink JDBC Socket ServiceTemplate (configured during the installation) is copied. Some of the settings may already be configured during installation. Check these values or correct these values for your specific service when you encounter them in the next steps.

  2. The SequeLink Server for JDBC Socket starts up the JVM and therefore it needs the shared library path to be set in the SequeLink configuration. This is done via a SequeLink Service environment variable.

    3. On Linux/UNIX, use the shared library path, as follows:

    shared_library_path =java_install_dir/shared_library_directory_for_the_jvm

    where:

    shared_library_path is one of the following values:

    Linux
    LD_LIBRARY_PATH
    HP-UX
    SHLIB_PATH
    AIX
    LIBPATH
    Solaris
    LD_LIBRARY_PATH
    z/OS USS
    LIBPATH

    shared_library_directory_for_the_jvm for J2SE 1.4 is one of the following values:

    Solaris
    lib/sparc/server
    HP-UX
    lib/PA_RISC/server
    AIX
    bin/classic
    Linux
    lib/i386/server
    z/OS USS
    bin/classic

    The shared library of the JVM of JRE 1.4 is one of the following values. It must reside in the shared_library_directory_for_the_jvm:

    Solaris
    libjvm.so
    HP-UX
    libjvm.sl
    AIX
    libjvm.a
    Linux
    libjvm.so
    z/OS USS
    libjvm.so

  3. The SequeLink Service for JDBC Socket attempts to load the JDBC drivers, defined in the server side data sources. All JDBC drivers that need to be accessed must reside in the CLASSPATH. This environment variable needs to be defined in the SequeLink service configuration. Add the CLASSPATH and the classes used by the SequeLink service for JDBC Socket. These classes are installed in install_dir/bin/odbc2jdbc/classes.

    4. For example, to configure SequeLink with the Apache Derby 10 driver:

    CLASSPATH=/opt/Apache/Derby/derby;
    /usr/slserver60/bin/classes

  4. Optionally, if you want to specify specific settings for the JVM, set the SequeLink Service environment variable SL_JAVA_OPTIONS.

    5. For example, to set the maximum heap size for the JVM, type:

    SL_JAVA_OPTIONS=-Xmx32M

    For example, for Derby, you may have to specify the database directory:

    SL_JAVA_OPTIONS= -DDerby.system.home=/usr/Data/derby

  5. Create a new server side data source or use the Default server side data source.
  6. Specify the required server-side data source settings for the JDBC driver.
    • DataSourceSOCJDBCConnectionURL

      • For example, for Apache Derby 10:

      DataSourceSOCJDBCConnectionURL = jdbc:dd-derby10:salesdb

      Where salesdb is the name of the database that you want to access.

    • DataSourceSOCJDBCDriverClassName

      • For example, for Apache Derby 10:

      DataSourceSOCJDBCDriverClassName = com.ddtek.jdbc.derby10.DerbyDriver

      See "SequeLink® Service Attributes" for information about these attributes.

  7. Specify specific, server-side data source settings, for your JDBC driver, for example, DataSourceSOCJDBCDbPropertiesName=derby.

    8. See "SequeLink® Service Attributes" for information about these attributes.

  8. When the SequeLink Service for JDBC Socket and its server-side data sources are set up, you can save your SequeLink configuration and start the SequeLink Service for JDBC Socket.
  9. Run your ODBC, JDBC, .NET or ADO application and access the databases through your JDBC backend driver using the SequeLink Service for JDBC Socket. Refer to the SequeLink Developer's Guide for additional information.

Using a SequeLink® Server for JDBC Socket Service on z/OS USS

Although you can start and stop SequeLink Service for JDBC Socket using the SequeLink Manager Snap-in, you might not want the users to log on to the MMC console and manually start the Service. Furthermore, the SequeLink Agent cannot be started this way because SequeLink Manager Snap-in requires the SequeLink Agent Service to be already up and running.

Four scripts are provided in the /install_dir/admin subdirectory to help you automate the starting and stopping of SequeLink services:

This information pertains to SequeLink on z/OS.

Configuring SequeLink® Service for JDBC Socket on z/OS USS

The configuration procedure for SequeLink Service for JDBC Socket on z/OS USS uses the steps described in "Configuring a SequeLink® Service for JDBC Socket on Linux/UNIX".

In addition to defining the connection URL and any required environment variables, you can configure the syslog daemon. See "Writing Syslog Messages" for more information.

In addition, read the following sections for platform-specific differences:

Starting SequeLink® Services

The SequeLink Agent Service is used to administer and control the SequeLink Service for JDBC Socket. For that reason, we recommend that you first start the SequeLink Agent Service before starting the SequeLink Service for JDBC Socket.

To start the SequeLink Service for JDBC, Socket use the startSLSocket2JDBC script located in the /install_dir/admin subdirectory.

You can start the scripts either from a shell or with the BPXBATCH utility program, which allows you to start the processes from a batch Job or Started Task. The SLUSS1 sample in the /install_dir/admin subdirectory shows how you can achieve this.

Use the following guidelines for starting the services:

  1. Define the UID associated with SequeLink Server processes.

    2. The OMVS UID associated with both UNIX processes must be the same, and the UID must be the owner of the SequeLink installation files or be superuser.

    During installation, the owner of the SequeLink libraries was set to the UID of the person who installed SequeLink. If you need to change the ownership of the installation files, you can do so with the following command:

    chown -R owner-uid installation_target_directory

    where owner-uid is the user ID of the new owner and installation_target_directory is the SequeLink installation directory.

  2. Define which UID is associated with SequeLink Server process.

    3. Typically, the UID is inherited from the UNIX parent process starting the script. However, the method you used to start the service determines which UID is used:

    • If started manually from a shell, the UID of the logged in user is inherited.
    • If started from a batch Job, the UID of the user submitting the batch Job is inherited.
    • If started from a started Task, the UID of the user associated with the started Task is inherited.
  3. Optionally, you can change the UID to the value of the Environment variable _BPX_USERID.
    • Set and export the _BPX_USERID environment variable in both the startSLAgent and startSLSocket2JDBC scripts to override the standard behavior.
    • Ensure the MVS user associated with the parent process has UPDATE access on the BPX.DAEMON profile in the FACILITY class.
  4. Define the JobName associated with SequeLink Server process.

    5. Typically, the user of the parent process is used and appended with a number to form the JobName. You can change this default behavior by setting the Environment variable _BPX_JOBNAME:

    • Set and export the _BPX_JOBNAME environment variable in the scripts. The startSLSocker2JDBC script provides an example.
    • Ensure the MVS user associated with the child process (not the parent process) has READ access to the BPX.JOBNAME profile in the FACILITY class.
Stopping SequeLink® Services

You can start the scripts that stop the SequeLink services from a shell, a batch Job, or a Started Task. Ensure the UID connected to either process has authority to access the SequeLink installation directories.

Writing Syslog Messages

In addition to the normal SequeLink logging that is written to the logging directory, SequeLink Server for JDBC Socket on z/OS USS writes messages to the z/OS USS syslog. The output destination of these messages is controlled by the syslog daemon.

The syslog daemon is shipped with IBM Communication Server, but it is not configured automatically. To configure the syslog daemon, refer to Communication Server - IP Configuration, "Configuring the Syslog Daemon (syslogd)".

By default, SequeLink writes syslog messages to the 'user' facility. You can configure the facility that SequeLink uses by setting the ServiceUnixSysLogFacility service attribute (see "ServiceUnixSyslogFacility").

For example, when added to the /etc/syslog.conf file, the following statement sends SequeLink syslog messages to the /var/log/user_sqlnk file: 

# Write ALL messages from applications, which specify 
# facility "user" such as SequeLink_USS log 
# 
user.* /var/log/user_sqlnk 
#

Tuning the SequeLink® Server for JDBC Socket Service on z/OS USS

Tuning can make a significant difference in the performance of your application. During the performance and scalability tests of this product, tuning improved throughput and response time in some cases by two to three times.

The SequeLink Server for JDBC Socket Service uses the Java Virtual Machine. You can tune this environment using the ServiceEnvironmentVariable SL_JAVA_OPTIONS. For example, to specify options used by the backend JDBC Driver: 

ServiceEnvironmentVariable=SL_JAVA_OPTIONS=-Xms32m -Xms64m -Xcomp -verbose

In the case of the SequeLink Server for JDBC Socket Service running on z/OS USS, the service runs with the IBM Language Environment (LE) runtime library under UNIX System Services on z/OS. The JDBC driver runs in the Java Virtual Machine (JVM), which also runs with the same IBM LE runtime library.

Tuning of this complex environment involves:

Tuning of UNIX System Services

Because both the SequeLink Server and the JVM use USS for z/OS for base operating system functions, USS must be correctly installed and tuned to get optimum performance.

These topics are discussed in IBM's document, UNIX System Services: Planning (GA22-7800-02), in the chapter "Tuning Performance." See also the IBM USS performance Web page:
http://www-1.ibm.com/servers/eserver/zseries/zos/unix/bpxa1tun.html for detailed tuning suggestions.

Also, using a performance monitor that supports USS is helpful.

Tuning of the IBM Language Environment

The settings of heap and stack sizes and the use of heap pools can positively influence the performance of your SequeLink Server for JDBC Socket on z/OS USS.

Heap and Stack Sizes

All of these storage settings need to be determined for your environment. A Language Environment (LE) storage report generated by the RPTSTG(ON) option shows you how much stack and heap storage is being used, the total number of segments allocated, and the recommended values for the various storage runtime options.

However, RPTSTG(ON) and the STORAGE runtime option can have a negative affect on the performance of your application, because as the application runs, statistics are kept on storage requests. Therefore, always use the IBM-supplied default setting RPTSTG(OFF) when running production jobs. Use RPTSTG(ON) and STORAGE only when debugging or tuning applications.

Refer to IBM's Language Environment Programming Guide (SA22-7561-02) and Language Environment Programming Reference (SA22-7562-02) for details.

Performance and tuning tips for LE can also be obtained from the IBM Web page:
http://www-1.ibm.com/servers/eserver/zseries/zos/le/

LE settings can be set in the SequeLink Server for JDBC Socket service using the environment variable _CEE_RUNOPTS.

For example: 

_CEE_RUNOPTS=HEAP(128M,8M,ANYWHERE,KEEP,8K,4K),
ANYHEAP(8M,512K,ANYWHERE,FREE),STORAGE(NONE,NONE,NONE,1K),
HEAPP(ON,8,1,32,1,128,2,256,1,1024,4,2048,2)

Heap Pools

Tuning the heap pools algorithm for an application is a three-step process that is described in IBM's Language Environment Programming Guide (SA22-7561-02).

Tuning of the Java Virtual Machine (JVM)

For hints and tips, consult the IBM JVM Web page:
http://www-1.ibm.com/servers/eserver/zseries/software/java/javafaq.html

Specific start-up settings for the JVM can be configured in the SequeLink for JDBC Socket service through the SequeLink Service environment variable.

For example, following are the JVM options used for the performance and scalability tests: 

IBM_JAVA_OPTIONS=-Xms32m -Xmx64m -Xcomp

Environment variables and command-line parameters for the JVM can be found in IBM® Developer Kit and Runtime Environment, Java™ 2 Technology Edition, Version 1.4.1, Service Refresh 1 Diagnostics Guide (SC34-6309-02).